home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / cmds / kdbx.man < prev    next >
Encoding:
Text File  |  1990-10-18  |  7.6 KB  |  180 lines
  1. ' $Header: /sprite/src/attcmds/kdbx/RCS/kdbx.man,v 1.2 90/10/18 12:13:48 kupfer Exp $ SPRITE (Berkeley)
  2. .so \*(]ltmac.sprite
  3. .HS KDBX cmds
  4. .BS
  5. .SH NAME
  6. kdbx \- Sprite debugger
  7. .SH SYNOPSIS
  8. kdbx [ \-ip ] [ \-I \fIdir\fP ] [ \-c \fIfile\fP ] [ \-h \fIhostname\fP ] [\fIobjfile\fP]
  9. .BE
  10. .SH DESCRIPTION
  11. kdbx is a debugger which can be used to debug the Sprite kernel.
  12. kdbx is nearly identical to dbx.
  13. The only difference is the relationship between the debugger (kdbx) and the
  14. debuggee (the kernel).
  15. This manual page describes how kdbx must be used differently because of the
  16. different debugging relationship.
  17. Since kdbx accepts all options and commands of dbx, these are not described
  18. in this manual page.
  19. A complete reference of all of the options and the commands
  20. accepted by kdbx is contained in dbx(1).
  21. .SH "Starting up Kdbx"
  22. The Sprite debugging facilities are broken into two pieces: the piece which
  23. resides in the Sprite kernel and kdbx which runs on a Unix machine.
  24. The Sprite kernel and kdbx communicate across a serial line or the ethernet.
  25. In order to use kdbx on the kernel, the kernel must be forced into the 
  26. debugging routine so that it can communicate to kdbx.
  27. Once this is accomplished, kdbx can be used on the kernel just like
  28. dbx can be used on a normal stopped process.
  29. Thus, the normal two step sequence needed to startup kdbx on the kernel is:
  30. .IP 1)
  31. Force the kernel into the debugging routine.
  32. The method of accomplishing this will be explained below.
  33. .IP 2)
  34. Invoke kdbx like dbx.
  35. For example, the normal command would be ``kdbx -I ../Installed/mod.o -h hostname sprite''.
  36. .PP
  37. It is also possible to invoke ``kdbx -p ...'' to indicate that kdbx should 
  38. read the symbol table but prompt the user before communicating with the Sprite
  39. kernel.  In this case, kdbx may be invoked before Sprite enters the debugger,
  40. thus overlapping some of the overhead of booting and debugging.
  41. .PP
  42. By default kdbx uses the serial line for debugging.
  43. The kernel on the other hand defaults to the network.
  44. In order to have kdbx use the network the -h flag must be used in order
  45. to specify the name of the host that is to be debugged.
  46. There are two methods of making the sprite kernel use the serial line instead
  47. of the network.
  48. First, the L1-B key described below can be used.
  49. Second, the kernel can be recompiled with the \fIdbg_Rs232Debug\fP flag set
  50. to TRUE (it is set to FALSE by the dbg module by default).
  51. This can be done in the mainHook.c file that is in each kernel's directory.
  52. .PP
  53. There are several different ways to force the kernel into the debugging routine.
  54. The first method of entering the debugging routine is by an unhandled 
  55. exception which the operating system encountered.
  56. If this happens then no further manipulation of the kernel is required and
  57. kdbx can be invoked directly.
  58. The second method is by putting a call to the debugger in the operating 
  59. system code.
  60. This is done by including dbg.h and entering the macro DBG_CALL at the point
  61. where you wish the debugger to be called.
  62. An example piece of C code which uses this macro is
  63. .sp 1
  64. .RS
  65. Sys_Printf("Kernel foobared");
  66. .br
  67. DBG_CALL;
  68. .RE
  69. .sp 1
  70. .LP
  71. If this method is used, then kdbx can be invoked directly.
  72. .PP
  73. If the kernel is not already in the debugging routine, then it must be
  74. interrupted and forced into the debugging routine.
  75. The easiest way to do this is to type \fBL1-D\fP at the console of the kernel
  76. being debugged.
  77. This will immediately force the kernel into the debugger
  78. and kdbx can be invoked on the kernel.
  79. In this case the debugger will use the network regardless of the value
  80. of the \fIdbg_Rs232Debug\fP flag.
  81. In order to use the serial line use \fBL1-B\fP instead.
  82. .PP
  83. Another simple way of forcing the kernel into the debugger is to issue the
  84. command ``l1d hostname'' which will send a debug message to the kernel.
  85. .PP
  86. A more complicated method of forcing the kernel into the debugger is:
  87. .IP 1)
  88. Type an \fBL1-A\fP at the console of the kernel being debugged.
  89. After typing this the program counter (PC) where the kernel was 
  90. interrupted will be printed out.
  91. .IP 2)
  92. Type the command \fBL a04008\fP \fIaddr\fP where \fIaddr\fP is the PC that 
  93. was printed out in step 1.
  94. .IP 3)
  95. Type the command \fBC a04006\fP.
  96. .LP
  97. After this last step the kernel debugger will have been entered and kdbx can
  98. now be invoked on the kernel.
  99. .SH "Using Kdbx"
  100. Once kdbx has been invoked on the kernel it can be used almost exactly 
  101. like dbx.
  102. All of the commands that work in dbx will also work in kdbx (i.e. 
  103. setting of breakpoints, single stepping, tracing, printing of variables,
  104. etc.).
  105. The only difference when using kdbx is 
  106. if after typing a ``cont'' command you wish to 
  107. interrupt the kernel to get back into kdbx.
  108. When using normal dbx a control-C can be typed at the terminal to interrupt the
  109. debugged process.
  110. This will not work with kdbx.
  111. In order to interrupt the kernel you must use the same method that was given
  112. above for entering the kernel debugging routine from the console.
  113. Once this is done then kdbx will get the interrupt.
  114. .SH "Quitting Kdbx"
  115. Kdbx can be exited just like dbx; that is, by using the ``quit'' command.
  116. When kdbx is exited the kernel will resume where kdbx tells it to resume.
  117. .SH "Additions to Kdbx"
  118. The part of the debugger which resides in the Sprite kernel saves 
  119. the state of the kernel when it is entered.
  120. Kdbx is aware of part of this state (such as the program counter and the
  121. general purpose registers) but is unaware of most of it.
  122. In order to get at this information the variables which contain this information
  123. can be printed out in kdbx by using the normal print command.
  124. These variables include:
  125. .IP dbgSfcReg        
  126. The source function code register.
  127. .IP dbgDfcReg
  128. The destination function code register.
  129. .IP dbgUserContext
  130. The user context register.
  131. .IP dbgKernelContext
  132. The kernel context register.
  133. .IP dbgTrapStack
  134. The stack that was created when the debugger was entered.
  135. This includes the bus error register, the user stack pointer,
  136. the 16 general purpose registers in the order d0-d7, a0-a7, and the
  137. exception stack.
  138. The exception stack includes the pc and the status register.
  139. See the header file exc.h for the exact format of the trap stack and the
  140. exception stack.
  141. .PP
  142. In the normal case kdbx will only backtrace the stack of the process that
  143. was executing when the debugger was entered.
  144. If you wish to backtrace the stack of some other waiting process then
  145. go through the following steps:
  146. .IP 1)
  147. Enter the command ``set $index = process-table-index'' where process-table-index
  148. is the index of the process control block of the process whose stack you
  149. want to trace.
  150. .IP 2)
  151. Now issue the normal ``where'' command.
  152. .IP 3)
  153. Go back to the original process by issuing the command ``set $index = 0''.
  154. .LP
  155. Note that the only command that should be executed after switching processes
  156. is the where command.
  157. Continuing the kernel after switching stacks would be a disaster.
  158. .SH "Modifications to Kdbx"
  159. There have been several modifications to kdbx:
  160. .IP 1)
  161. Parameter types are not checked when calling functions inside of kdbx.
  162. .IP 2)
  163. Objects of type ``char *'' are not dereferenced automatically.
  164. There are two ways to make them be dereferenced while using the ``print''
  165. command.
  166. One is to issue the command ``ps'' (an alias for print string)  
  167. instead of ``print''.
  168. The other is to automatically set the variable
  169. $dref (i.e. use the command ``set $dref'').
  170. This will make all subsequent ``print'' commands dereference strings.
  171. .SH BUGS
  172. A good chunk of this man page is out of date.  We currently only use
  173. kdbx on Decstation 3100s.  Other machines use kgdb, and we plan to
  174. switch 3100s to kgdb, too.  Look at the script
  175. /sprite/src/kernel/sprite/Kdbx for the correct way to invoke kdbx.
  176. .SH "SEE ALSO"
  177. dbx, kgdb
  178. .SH KEYWORDS
  179. debugger, dbx, sprite debugger, kernel debugger
  180.